
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>calc_surface_energy_static.py &#8212; iprPy 0.10.2 documentation</title>
    <link rel="stylesheet" href="../../_static/basic.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
    <script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
    <script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"inlineMath": [["$", "$"], ["\\(", "\\)"]], "processEscapes": true, "ignoreClass": "document", "processClass": "math|output_area"}})</script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Jupyter Demonstration Notebooks" href="../../notebook_styles.html" />
    <link rel="prev" title="Input script parameters" href="parameters.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="../../notebook_styles.html" title="Jupyter Demonstration Notebooks"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="parameters.html" title="Input script parameters"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../../index.html">iprPy 0.10.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../../calculation_styles.html" >Calculation Styles</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="index.html" accesskey="U">surface_energy_static</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="calc-surface-energy-static-py">
<h1>calc_surface_energy_static.py<a class="headerlink" href="#calc-surface-energy-static-py" title="Permalink to this headline">¶</a></h1>
<div class="section" id="module-iprPy.calculation.surface_energy_static.calc_surface_energy_static">
<span id="calculation-script-functions"></span><h2>Calculation script functions<a class="headerlink" href="#module-iprPy.calculation.surface_energy_static.calc_surface_energy_static" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="iprPy.calculation.surface_energy_static.calc_surface_energy_static.main">
<code class="sig-name descname">main</code><span class="sig-paren">(</span><em class="sig-param">*args</em><span class="sig-paren">)</span><a class="headerlink" href="#iprPy.calculation.surface_energy_static.calc_surface_energy_static.main" title="Permalink to this definition">¶</a></dt>
<dd><p>Main function called when script is executed directly.</p>
</dd></dl>

<dl class="function">
<dt id="iprPy.calculation.surface_energy_static.calc_surface_energy_static.process_input">
<code class="sig-name descname">process_input</code><span class="sig-paren">(</span><em class="sig-param">input_dict</em>, <em class="sig-param">UUID=None</em>, <em class="sig-param">build=True</em><span class="sig-paren">)</span><a class="headerlink" href="#iprPy.calculation.surface_energy_static.calc_surface_energy_static.process_input" title="Permalink to this definition">¶</a></dt>
<dd><p>Processes str input parameters, assigns default values if needed, and
generates new, more complex terms as used by the calculation.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>input_dict</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.8)"><em>dict</em></a>) – Dictionary containing the calculation input parameters with string
values.  The allowed keys depends on the calculation style.</p></li>
<li><p><strong>UUID</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.8)"><em>str</em></a><em>, </em><em>optional</em>) – Unique identifier to use for the calculation instance.  If not
given and a ‘UUID’ key is not in input_dict, then a random UUID4
hash tag will be assigned.</p></li>
<li><p><strong>build</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.8)"><em>bool</em></a><em>, </em><em>optional</em>) – Indicates if all complex terms are to be built.  A value of False
allows for default values to be assigned even if some inputs
required by the calculation are incomplete.  (Default is True.)</p></li>
</ul>
</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="iprPy.calculation.surface_energy_static.calc_surface_energy_static.relax_system">
<code class="sig-name descname">relax_system</code><span class="sig-paren">(</span><em class="sig-param">lammps_command</em>, <em class="sig-param">system</em>, <em class="sig-param">potential</em>, <em class="sig-param">mpi_command=None</em>, <em class="sig-param">etol=0.0</em>, <em class="sig-param">ftol=0.0</em>, <em class="sig-param">maxiter=10000</em>, <em class="sig-param">maxeval=100000</em>, <em class="sig-param">dmax=0.01</em>, <em class="sig-param">lammps_date=None</em><span class="sig-paren">)</span><a class="headerlink" href="#iprPy.calculation.surface_energy_static.calc_surface_energy_static.relax_system" title="Permalink to this definition">¶</a></dt>
<dd><p>Sets up and runs the min.in LAMMPS script for performing an energy/force
minimization to relax a system.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>lammps_command</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.8)"><em>str</em></a>) – Command for running LAMMPS.</p></li>
<li><p><strong>system</strong> (<em>atomman.System</em>) – The system to perform the calculation on.</p></li>
<li><p><strong>potential</strong> (<em>atomman.lammps.Potential</em>) – The LAMMPS implemented potential to use.</p></li>
<li><p><strong>mpi_command</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.8)"><em>str</em></a><em>, </em><em>optional</em>) – The MPI command for running LAMMPS in parallel.  If not given, LAMMPS
will run serially.</p></li>
<li><p><strong>etol</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.8)"><em>float</em></a><em>, </em><em>optional</em>) – The energy tolerance for the structure minimization. This value is
unitless. (Default is 0.0).</p></li>
<li><p><strong>ftol</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.8)"><em>float</em></a><em>, </em><em>optional</em>) – The force tolerance for the structure minimization. This value is in
units of force. (Default is 0.0).</p></li>
<li><p><strong>maxiter</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.8)"><em>int</em></a><em>, </em><em>optional</em>) – The maximum number of minimization iterations to use (default is
10000).</p></li>
<li><p><strong>maxeval</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.8)"><em>int</em></a><em>, </em><em>optional</em>) – The maximum number of minimization evaluations to use (default is
100000).</p></li>
<li><p><strong>dmax</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.8)"><em>float</em></a><em>, </em><em>optional</em>) – The maximum distance in length units that any atom is allowed to relax
in any direction during a single minimization iteration (default is
0.01 Angstroms).</p></li>
<li><p><strong>lammps_date</strong> (<a class="reference external" href="https://docs.python.org/3/library/datetime.html#datetime.date" title="(in Python v3.8)"><em>datetime.date</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.8)"><em>None</em></a><em>, </em><em>optional</em>) – The date version of the LAMMPS executable.  If None, will be identified
from the lammps_command (default is None).</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p>Dictionary of results consisting of keys:</p>
<ul class="simple">
<li><p><strong>’logfile’</strong> (<em>str</em>) - The name of the LAMMPS log file.</p></li>
<li><p><strong>’initialdatafile’</strong> (<em>str</em>) - The name of the LAMMPS data file
used to import an inital configuration.</p></li>
<li><p><strong>’initialdumpfile’</strong> (<em>str</em>) - The name of the LAMMPS dump file
corresponding to the inital configuration.</p></li>
<li><p><strong>’finaldumpfile’</strong> (<em>str</em>) - The name of the LAMMPS dump file
corresponding to the relaxed configuration.</p></li>
<li><p><strong>’potentialenergy’</strong> (<em>float</em>) - The total potential energy of
the relaxed system.</p></li>
</ul>
</p>
</dd>
<dt class="field-odd">Return type</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.8)">dict</a></p>
</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="iprPy.calculation.surface_energy_static.calc_surface_energy_static.surface_energy">
<code class="sig-name descname">surface_energy</code><span class="sig-paren">(</span><em class="sig-param">lammps_command</em>, <em class="sig-param">ucell</em>, <em class="sig-param">potential</em>, <em class="sig-param">hkl</em>, <em class="sig-param">mpi_command=None</em>, <em class="sig-param">sizemults=None</em>, <em class="sig-param">minwidth=None</em>, <em class="sig-param">even=False</em>, <em class="sig-param">conventional_setting='p'</em>, <em class="sig-param">cutboxvector='c'</em>, <em class="sig-param">atomshift=None</em>, <em class="sig-param">shiftindex=None</em>, <em class="sig-param">etol=0.0</em>, <em class="sig-param">ftol=0.0</em>, <em class="sig-param">maxiter=10000</em>, <em class="sig-param">maxeval=100000</em>, <em class="sig-param">dmax=0.01</em><span class="sig-paren">)</span><a class="headerlink" href="#iprPy.calculation.surface_energy_static.calc_surface_energy_static.surface_energy" title="Permalink to this definition">¶</a></dt>
<dd><p>Evaluates surface formation energies by slicing along one periodic
boundary of a bulk system.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>lammps_command</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.8)"><em>str</em></a>) – Command for running LAMMPS.</p></li>
<li><p><strong>ucell</strong> (<em>atomman.System</em>) – The crystal unit cell to use as the basis of the stacking fault
configurations.</p></li>
<li><p><strong>potential</strong> (<em>atomman.lammps.Potential</em>) – The LAMMPS implemented potential to use.</p></li>
<li><p><strong>hkl</strong> (<em>array-like object</em>) – The Miller(-Bravais) crystal fault plane relative to ucell.</p></li>
<li><p><strong>mpi_command</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.8)"><em>str</em></a><em>, </em><em>optional</em>) – The MPI command for running LAMMPS in parallel.  If not given, LAMMPS
will run serially.</p></li>
<li><p><strong>sizemults</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#list" title="(in Python v3.8)"><em>list</em></a><em> or </em><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#tuple" title="(in Python v3.8)"><em>tuple</em></a><em>, </em><em>optional</em>) – The three System.supersize multipliers [a_mult, b_mult, c_mult] to use on the
rotated cell to build the final system. Note that the cutboxvector sizemult
must be an integer and not a tuple.  Default value is [1, 1, 1].</p></li>
<li><p><strong>minwidth</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.8)"><em>float</em></a><em>, </em><em>optional</em>) – If given, the sizemult along the cutboxvector will be selected such that the
width of the resulting final system in that direction will be at least this
value. If both sizemults and minwidth are given, then the larger of the two
in the cutboxvector direction will be used.</p></li>
<li><p><strong>even</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.8)"><em>bool</em></a><em>, </em><em>optional</em>) – A True value means that the sizemult for cutboxvector will be made an even
number by adding 1 if it is odd.  Default value is False.</p></li>
<li><p><strong>conventional_setting</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.8)"><em>str</em></a><em>, </em><em>optional</em>) – Allows for rotations of a primitive unit cell to be determined from
(hkl) indices specified relative to a conventional unit cell.  Allowed
settings: ‘p’ for primitive (no conversion), ‘f’ for face-centered,
‘i’ for body-centered, and ‘a’, ‘b’, or ‘c’ for side-centered.  Default
behavior is to perform no conversion, i.e. take (hkl) relative to the
given ucell.</p></li>
<li><p><strong>cutboxvector</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.8)"><em>str</em></a><em>, </em><em>optional</em>) – Indicates which of the three system box vectors, ‘a’, ‘b’, or ‘c’, to
cut with a non-periodic boundary (default is ‘c’).</p></li>
<li><p><strong>atomshift</strong> (<em>array-like object</em><em>, </em><em>optional</em>) – A Cartesian vector shift to apply to all atoms.  Can be used to shift
atoms perpendicular to the fault plane to allow different termination
planes to be cut.  Cannot be given with shiftindex.</p></li>
<li><p><strong>shiftindex</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.8)"><em>int</em></a><em>, </em><em>optional</em>) – Allows for selection of different termination planes based on the
preferred shift values determined by the underlying fault generation.
Cannot be given with atomshift. If neither atomshift nor shiftindex
given, then shiftindex will be set to 0.</p></li>
<li><p><strong>etol</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.8)"><em>float</em></a><em>, </em><em>optional</em>) – The energy tolerance for the structure minimization. This value is
unitless. (Default is 0.0).</p></li>
<li><p><strong>ftol</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.8)"><em>float</em></a><em>, </em><em>optional</em>) – The force tolerance for the structure minimization. This value is in
units of force. (Default is 0.0).</p></li>
<li><p><strong>maxiter</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.8)"><em>int</em></a><em>, </em><em>optional</em>) – The maximum number of minimization iterations to use (default is
10000).</p></li>
<li><p><strong>maxeval</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.8)"><em>int</em></a><em>, </em><em>optional</em>) – The maximum number of minimization evaluations to use (default is
100000).</p></li>
<li><p><strong>dmax</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.8)"><em>float</em></a><em>, </em><em>optional</em>) – The maximum distance in length units that any atom is allowed to relax
in any direction during a single minimization iteration (default is
0.01 Angstroms).</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p><p>Dictionary of results consisting of keys:</p>
<ul class="simple">
<li><p><strong>’dumpfile_base’</strong> (<em>str</em>) - The filename of the LAMMPS dump file
of the relaxed bulk system.</p></li>
<li><p><strong>’dumpfile_surf’</strong> (<em>str</em>) - The filename of the LAMMPS dump file
of the relaxed system containing the free surfaces.</p></li>
<li><p><strong>’E_total_base’</strong> (<em>float</em>) - The total potential energy of the
relaxed bulk system.</p></li>
<li><p><strong>’E_total_surf’</strong> (<em>float</em>) - The total potential energy of the
relaxed system containing the free surfaces.</p></li>
<li><p><strong>’A_surf’</strong> (<em>float</em>) - The area of the free surface.</p></li>
<li><p><strong>’E_coh’</strong> (<em>float</em>) - The cohesive energy of the relaxed bulk
system.</p></li>
<li><p><strong>’E_surf_f’</strong> (<em>float</em>) - The computed surface formation energy.</p></li>
</ul>
</p>
</dd>
<dt class="field-odd">Return type</dt>
<dd class="field-odd"><p><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.8)">dict</a></p>
</dd>
<dt class="field-even">Raises</dt>
<dd class="field-even"><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#ValueError" title="(in Python v3.8)"><strong>ValueError</strong></a> – For invalid cutboxvectors</p>
</dd>
</dl>
</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../index.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">calc_surface_energy_static.py</a><ul>
<li><a class="reference internal" href="#module-iprPy.calculation.surface_energy_static.calc_surface_energy_static">Calculation script functions</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="parameters.html"
                        title="previous chapter">Input script parameters</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="../../notebook_styles.html"
                        title="next chapter">Jupyter Demonstration Notebooks</a></p>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../../py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="../../notebook_styles.html" title="Jupyter Demonstration Notebooks"
             >next</a> |</li>
        <li class="right" >
          <a href="parameters.html" title="Input script parameters"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../../index.html">iprPy 0.10.2 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="../../calculation_styles.html" >Calculation Styles</a> &#187;</li>
          <li class="nav-item nav-item-2"><a href="index.html" >surface_energy_static</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 2.1.2.
    </div>
  </body>
</html>